home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 52 / Amiga Format AFCD52 (Issue 136, May 2000).iso / -serious- / programming / c / icu-1.3.1 / icu-bin / include / udat.h < prev    next >
C/C++ Source or Header  |  2000-02-23  |  18KB  |  457 lines
  1. /*
  2. *******************************************************************************
  3. *                                                                             *
  4. * COPYRIGHT:                                                                  *
  5. *   (C) Copyright Taligent, Inc.,  1996                                       *
  6. *   (C) Copyright International Business Machines Corporation,  1998-1999     *
  7. *   Licensed Material - Program-Property of IBM - All Rights Reserved.        *
  8. *   US Government Users Restricted Rights - Use, duplication, or disclosure   *
  9. *   restricted by GSA ADP Schedule Contract with IBM Corp.                    *
  10. *                                                                             *
  11. *******************************************************************************
  12. */
  13.  
  14. #ifndef UDAT_H
  15. #define UDAT_H
  16.  
  17. #include "utypes.h"
  18. #include "ucal.h"
  19. #include "unum.h"
  20. /**
  21.  * Date Format C API  consists of functions that convert dates and
  22.  * times from their internal representations to textual form and back again in a
  23.  * language-independent manner. Converting from the internal representation (milliseconds
  24.  * since midnight, January 1, 1970) to text is known as "formatting," and converting
  25.  * from text to millis is known as "parsing."  We currently define only one concrete
  26.  * structure UDateFormat, which can handle pretty much all normal
  27.  * date formatting and parsing actions.
  28.  * <P>
  29.  * Date Format helps you to format and parse dates for any locale. Your code can
  30.  * be completely independent of the locale conventions for months, days of the
  31.  * week, or even the calendar format: lunar vs. solar.
  32.  * <P>
  33.  * To format a date for the current Locale with default time and date style, 
  34.  * use one of the static factory methods:
  35.  * <pre>
  36.  * .    UErrorCode status;
  37.  * .    UFieldPosition pos;
  38.  * .    UChar *myString;
  39.  * .    t_int32 myStrlen=0;
  40.  * .    UDateFormat* dfmt = udat_open(UCAL_DEFAULT, UCAL_DEFAULT, NULL, "PST", &status);
  41.  * .    myStrlen = udat_format(dfmt, myDate, NULL, myStrlen, &pos, &status);
  42.  * .    if(status==U_BUFFER_OVERFLOW_ERROR){
  43.  * .    status=U_ZERO_ERROR;
  44.  * .    myString=(UChar*)malloc(sizeof(UChar) * (myStrlen+1) );
  45.  * .    udat_format(dfmt, myDate, myString, myStrlen+1, &pos, &status);
  46.  * .    }
  47.  * </pre>
  48.  * If you are formatting multiple numbers, it is more efficient to get the
  49.  * format and use it multiple times so that the system doesn't have to fetch the
  50.  * information about the local language and country conventions multiple times.
  51.  * <pre>
  52.  * .    t_int32 i, myStrlen=0;
  53.  * .    UChar* myString;
  54.  * .    UDate myDateArr[] = { 0.0, 100000000.0, 2000000000.0 }; // test values
  55.  * .    UDateFormat* df = udat_open(UCAL_DEFAULT, UCAL_DEFAULT, NULL, "GMT", &status);
  56.  * .    for (i = 0; i < 3; ++i) {
  57.  * .    myStrlen = udat_format(df, myDate, NULL, myStrlen, &pos, &status);
  58.  * .    if(status==U_BUFFER_OVERFLOW_ERROR){
  59.  * .    status=U_ZERO_ERROR;
  60.  * .    myString=(UChar*)malloc(sizeof(UChar) * (myStrlen+1) );
  61.  * .    udat_format(df, myDate, myString, myStrlen+1, &pos, &status);
  62.  * .    }
  63.  * .    printf("%s \n", austrdup(myString) ); //austrdup( a function used to convert UChar* to char*)
  64.  * .    free(myString);
  65.  * .    }
  66.  * </pre>
  67.  * To format a date for a different Locale, specify it in the call to
  68.  * udat_open()
  69.  * <pre>
  70.  * .       UDateFormat* df = udat_open(UDAT_SHORT, UDAT_SHORT, "fr_FR", "GMT", &status);
  71.  * </pre>
  72.  * You can use a DateFormat API udat_parse() to parse.
  73.  * <pre>
  74.  * .       UErrorCode status = U_ZERO_ERROR;
  75.  * .       t_int32 parsepos=0;     
  76.  * .       UDate myDate = udat_parse(df, myString, u_strlen(myString), &parsepos, &status);
  77.  * </pre>
  78.  * . You can pass in different options for the arguments for date and time style 
  79.  * . to control the length of the result; from SHORT to MEDIUM to LONG to FULL. 
  80.  * . The exact result depends on the locale, but generally:
  81.  * . see UDateFormatStyle for more details
  82.  * <ul type=round>
  83.  *   <li>   UDAT_SHORT is completely numeric, such as 12/13/52 or 3:30pm
  84.  *   <li>   UDAT_MEDIUM is longer, such as Jan 12, 1952
  85.  *   <li>   UDAT_LONG is longer, such as January 12, 1952 or 3:30:32pm
  86.  *   <li>   UDAT_FULL is pretty completely specified, such as
  87.  *          Tuesday, April 12, 1952 AD or 3:30:42pm PST.
  88.  * </ul>
  89.  * You can also set the time zone on the format if you wish. 
  90.  * <P>
  91.  * You can also use forms of the parse and format methods with Parse Position and
  92.  * UFieldPosition to allow you to
  93.  * <ul type=round>
  94.  *   <li>   Progressively parse through pieces of a string.
  95.  *   <li>   Align any particular field, or find out where it is for selection
  96.  *          on the screen.
  97.  * </ul>
  98.  */
  99. /** A date formatter */
  100. typedef void* UDateFormat;
  101.  
  102. /** The possible date/time format styles */
  103. enum UDateFormatStyle {
  104.     /** Full style */
  105.     UDAT_FULL,
  106.     /** Long style */
  107.     UDAT_LONG,
  108.     /** Medium style */
  109.     UDAT_MEDIUM,
  110.     /** Short style */
  111.     UDAT_SHORT,
  112.     /** Default style */
  113.     UDAT_DEFAULT = UDAT_MEDIUM,
  114.     /** No style */
  115.     UDAT_NONE = -1
  116. };
  117. typedef enum UDateFormatStyle UDateFormatStyle;
  118.  
  119. /**
  120. * Open a new UDateFormat for formatting and parsing dates and times.
  121. * A UDateFormat may be used to format dates in calls to \Ref{udat_format},
  122. * and to parse dates in calls to \Ref{udat_parse}.
  123. * @param timeStyle The style used to format times; one of UDAT_FULL_STYLE, UDAT_LONG_STYLE, 
  124. * UDAT_MEDIUM_STYLE, UDAT_SHORT_STYLE, or UDAT_DEFAULT_STYLE
  125. * @param dateStyle The style used to format dates; one of UDAT_FULL_STYLE, UDAT_LONG_STYLE, 
  126. * UDAT_MEDIUM_STYLE, UDAT_SHORT_STYLE, or UDAT_DEFAULT_STYLE
  127. * @param locale The locale specifying the formatting conventions
  128. * @param tzID A timezone ID specifying the timezone to use.  If 0, use
  129. * the default timezone.
  130. * @param tzIDLength The length of tzID, or -1 if null-terminated.
  131. * @param status A pointer to an UErrorCode to receive any errors
  132. * @return A pointer to a UDateFormat to use for formatting dates and times, or 0 if
  133. * an error occurred.
  134. * @see udat_openPattern
  135. */
  136. U_CAPI UDateFormat*
  137. udat_open(UDateFormatStyle  timeStyle, 
  138.           UDateFormatStyle  dateStyle,
  139.           const char        *locale,
  140.       const UChar       *tzID,
  141.       int32_t           tzIDLength,
  142.           UErrorCode        *status);
  143.  
  144. /**
  145. * Open a new UDateFormat for formatting dates and times.
  146. * A UDateFormat may be used to format dates in calls to \Ref{udat_format},
  147. * and to parse dates in calls to \Ref{udat_parse}.
  148. * @param pattern A pattern specifying the format to use.
  149. * @param patternLength The number of characters in the pattern, or -1 if null-terminated.
  150. * @param locale The locale specifying the formatting conventions
  151. * @param status A pointer to an UErrorCode to receive any errors
  152. * @return A pointer to a UDateFormat to use for formatting dates and times, or 0 if
  153. * an error occurred.
  154. * @see udat_open
  155. */
  156. U_CAPI UDateFormat*
  157. udat_openPattern(    const   UChar           *pattern, 
  158.             int32_t         patternLength,
  159.             const   char         *locale,
  160.             UErrorCode      *status);
  161.  
  162. /**
  163. * Close a UDateFormat.
  164. * Once closed, a UDateFormat may no longer be used.
  165. * @param fmt The formatter to close.
  166. */
  167. U_CAPI void
  168. udat_close(UDateFormat* format);
  169.  
  170. /**
  171.  * Open a copy of a UDateFormat.
  172.  * This function performs a deep copy.
  173.  * @param fmt The format to copy
  174.  * @param status A pointer to an UErrorCode to receive any errors.
  175.  * @return A pointer to a UDateFormat identical to fmt.
  176.  */
  177. U_CAPI UDateFormat*
  178. udat_clone(const UDateFormat *fmt,
  179.        UErrorCode *status);
  180.  
  181. /**
  182. * Format a date using an UDateFormat.
  183. * The date will be formatted using the conventions specified in \Ref{udat_open}
  184. * or \Ref{udat_openPattern}
  185. * @param format The formatter to use
  186. * @param dateToFormat The date to format
  187. * @param result A pointer to a buffer to receive the formatted number.
  188. * @param resultLength The maximum size of result.
  189. * @param pos If not 0, a UFieldPosition which will receive the information on a specific field.
  190. * @param status A pointer to an UErrorCode to receive any errors
  191. * @return The total buffer size needed; if greater than resultLength, the output was truncated.
  192. * @see udat_parse
  193. */
  194. U_CAPI int32_t
  195. udat_format(    const    UDateFormat*    format,
  196.                         UDate           dateToFormat,
  197.                         UChar*          result,
  198.                         int32_t         resultLength,
  199.                         UFieldPosition* position,
  200.                         UErrorCode*     status);
  201.  
  202. /**
  203. * Parse a string into an date/time using a UDateFormat.
  204. * The date will be parsed using the conventions specified in \Ref{udat_open}
  205. * or \Ref{udat_openPattern}
  206. * @param fmt The formatter to use.
  207. * @param text The text to parse.
  208. * @param textLength The length of text, or -1 if null-terminated.
  209. * @param parsePos If not 0, on input a pointer to an integer specifying the offset at which
  210. * to begin parsing.  If not 0, on output the offset at which parsing ended.
  211. * @param status A pointer to an UErrorCode to receive any errors
  212. * @return The value of the parsed date/time
  213. * @see udat_format
  214. */
  215. U_CAPI UDate
  216. udat_parse(    const    UDateFormat*    format,
  217.             const    UChar*          text,
  218.                     int32_t         textLength,
  219.                     int32_t         *parsePos,
  220.                     UErrorCode      *status);
  221.  
  222. /**
  223. * Determine if an UDateFormat will perform lenient parsing.
  224. * With lenient parsing, the parser may use heuristics to interpret inputs that do not 
  225. * precisely match the pattern. With strict parsing, inputs must match the pattern. 
  226. * @param fmt The formatter to query
  227. * @return TRUE if fmt is set to perform lenient parsing, FALSE otherwise.
  228. * @see udat_setLenient
  229. */
  230. U_CAPI bool_t
  231. udat_isLenient(const UDateFormat* fmt);
  232.  
  233. /**
  234. * Specify whether an UDateFormat will perform lenient parsing.
  235. * With lenient parsing, the parser may use heuristics to interpret inputs that do not 
  236. * precisely match the pattern. With strict parsing, inputs must match the pattern. 
  237. * @param fmt The formatter to set
  238. * @param isLenient TRUE if fmt should perform lenient parsing, FALSE otherwise.
  239. * @see dat_isLenient
  240. */
  241. U_CAPI void
  242. udat_setLenient(    UDateFormat*    fmt,
  243.                     bool_t          isLenient);
  244.  
  245. /**
  246. * Get the UCalendar associated with an UDateFormat.
  247. * A UDateFormat uses a UCalendar to convert a raw value to, for example,
  248. * the day of the week.
  249. * @param fmt The formatter to query.
  250. * @return A pointer to the UCalendar used by fmt.
  251. * @see udat_setCalendar
  252. */
  253. U_CAPI const UCalendar*
  254. udat_getCalendar(const UDateFormat* fmt);
  255.  
  256. /**
  257. * Set the UCalendar associated with an UDateFormat.
  258. * A UDateFormat uses a UCalendar to convert a raw value to, for example,
  259. * the day of the week.
  260. * @param fmt The formatter to set.
  261. * @param calendarToSet A pointer to an UCalendar to be used by fmt.
  262. * @see udat_setCalendar
  263. */
  264. U_CAPI void
  265. udat_setCalendar(            UDateFormat*    fmt,
  266.                     const   UCalendar*      calendarToSet);
  267.  
  268. /**
  269. * Get the UNumberFormat associated with an UDateFormat.
  270. * A UDateFormat uses a UNumberFormat to format numbers within a date,
  271. * for example the day number.
  272. * @param fmt The formatter to query.
  273. * @return A pointer to the UNumberFormat used by fmt to format numbers.
  274. * @see udat_setNumberFormat
  275. */
  276. U_CAPI const UNumberFormat*
  277. udat_getNumberFormat(const UDateFormat* fmt);
  278.  
  279. /**
  280. * Set the UNumberFormat associated with an UDateFormat.
  281. * A UDateFormat uses a UNumberFormat to format numbers within a date,
  282. * for example the day number.
  283. * @param fmt The formatter to set.
  284. * @param numberFormatToSet A pointer to the UNumberFormat to be used by fmt to format numbers.
  285. * @see udat_getNumberFormat
  286. */
  287. U_CAPI void
  288. udat_setNumberFormat(            UDateFormat*    fmt,
  289.                         const   UNumberFormat*  numberFormatToSet);
  290.  
  291. /**
  292. * Get a locale for which date/time formatting patterns are available.
  293. * A UDateFormat in a locale returned by this function will perform the correct
  294. * formatting and parsing for the locale.
  295. * @param index The index of the desired locale.
  296. * @return A locale for which date/time formatting patterns are available, or 0 if none.
  297. * @see udat_countAvailable
  298. */
  299. U_CAPI const char*
  300. udat_getAvailable(int32_t index);
  301.  
  302. /**
  303. * Determine how many locales have date/time  formatting patterns available.
  304. * This function is most useful as determining the loop ending condition for
  305. * calls to \Ref{udat_getAvailable}.
  306. * @return The number of locales for which date/time formatting patterns are available.
  307. * @see udat_getAvailable
  308. */
  309. U_CAPI int32_t
  310. udat_countAvailable(void);
  311.  
  312. /**
  313. * Get the year relative to which all 2-digit years are interpreted.
  314. * For example, if the 2-digit start year is 2100, the year 99 will be
  315. * interpreted as 2199.
  316. * @param fmt The formatter to query.
  317. * @param status A pointer to an UErrorCode to receive any errors
  318. * @return The year relative to which all 2-digit years are interpreted.
  319. * @see udat_Set2DigitYearStart
  320. */
  321. U_CAPI UDate
  322. udat_get2DigitYearStart(    const   UDateFormat     *fmt,
  323.                                     UErrorCode      *status);
  324.  
  325. /**
  326. * Set the year relative to which all 2-digit years will be interpreted.
  327. * For example, if the 2-digit start year is 2100, the year 99 will be
  328. * interpreted as 2199.
  329. * @param fmt The formatter to set.
  330. * @param d The year relative to which all 2-digit years will be interpreted.
  331. * @param status A pointer to an UErrorCode to receive any errors
  332. * @see udat_Set2DigitYearStart
  333. */
  334. U_CAPI void
  335. udat_set2DigitYearStart(    UDateFormat     *fmt,
  336.                             UDate           d,
  337.                             UErrorCode      *status);
  338.  
  339. /**
  340. * Extract the pattern from a UDateFormat.
  341. * The pattern will follow the pattern syntax rules.
  342. * @param fmt The formatter to query.
  343. * @param localized TRUE if the pattern should be localized, FALSE otherwise.
  344. * @param result A pointer to a buffer to receive the pattern.
  345. * @param resultLength The maximum size of result.
  346. * @param status A pointer to an UErrorCode to receive any errors
  347. * @return The total buffer size needed; if greater than resultLength, the output was truncated.
  348. * @see udat_applyPattern
  349. */
  350. U_CAPI int32_t
  351. udat_toPattern(    const   UDateFormat     *fmt,
  352.                         bool_t          localized,
  353.                         UChar           *result,
  354.                         int32_t         resultLength,
  355.                         UErrorCode      *status);
  356.  
  357. /**
  358. * Set the pattern used by an UDateFormat.
  359. * The pattern should follow the pattern syntax rules.
  360. * @param fmt The formatter to set.
  361. * @param localized TRUE if the pattern is localized, FALSE otherwise.
  362. * @param pattern The new pattern
  363. * @param patternLength The length of pattern, or -1 if null-terminated.
  364. * @see udat_toPattern
  365. */
  366. U_CAPI void
  367. udat_applyPattern(            UDateFormat     *format,
  368.                             bool_t          localized,
  369.                     const   UChar           *pattern,
  370.                             int32_t         patternLength);
  371.  
  372. /** The possible types of date format symbols */
  373. enum UDateFormatSymbolType {
  374.     /** The era names, for example AD */
  375.     UDAT_ERAS,
  376.     /** The month names, for example February */
  377.     UDAT_MONTHS,
  378.     /** The short month names, for example Feb. */
  379.     UDAT_SHORT_MONTHS,
  380.     /** The weekday names, for example Monday */
  381.     UDAT_WEEKDAYS,
  382.     /** The short weekday names, for example Mon. */
  383.     UDAT_SHORT_WEEKDAYS,
  384.     /** The AM/PM names, for example AM */
  385.     UDAT_AM_PMS,
  386.     /** The localized characters */
  387.     UDAT_LOCALIZED_CHARS
  388. };
  389. typedef enum UDateFormatSymbolType UDateFormatSymbolType;
  390.  
  391. /** Date format symbols */
  392. struct UDateFormatSymbols;
  393. typedef struct UDateFormatSymbols UDateFormatSymbols;
  394.  
  395. /**
  396. * Get the symbols associated with an UDateFormat.
  397. * The symbols are what a UDateFormat uses to represent locale-specific data,
  398. * for example month or day names.
  399. * @param fmt The formatter to query.
  400. * @param type The type of symbols to get.  One of UDAT_ERAS, UDAT_MONTHS, UDAT_SHORT_MONTHS, 
  401. * UDAT_WEEKDAYS, UDAT_SHORT_WEEKDAYS, UDAT_AM_PMS, or UDAT_LOCALIZED_CHARS
  402. * @param index The desired symbol of type type.
  403. * @param result A pointer to a buffer to receive the pattern.
  404. * @param resultLength The maximum size of result.
  405. * @param status A pointer to an UErrorCode to receive any errors
  406. * @return The total buffer size needed; if greater than resultLength, the output was truncated.
  407. * @see udat_countSymbols
  408. * @see udat_setSymbols
  409. */
  410. U_CAPI int32_t
  411. udat_getSymbols(const   UDateFormat             *fmt,
  412.                         UDateFormatSymbolType   type,
  413.                         int32_t                 index,
  414.                         UChar                   *result,
  415.                         int32_t                 resultLength,
  416.                         UErrorCode              *status);
  417.  
  418. /**
  419. * Count the number of particular symbols for an UDateFormat.
  420. * This function is most useful as for detemining the loop termination condition
  421. * for calls to \Ref{udat_getSymbols}.
  422. * @param fmt The formatter to query.
  423. * @param type The type of symbols to count.  One of UDAT_ERAS, UDAT_MONTHS, UDAT_SHORT_MONTHS, 
  424. * UDAT_WEEKDAYS, UDAT_SHORT_WEEKDAYS, UDAT_AM_PMS, or UDAT_LOCALIZED_CHARS
  425. * @return The number of symbols of type type.
  426. * @see udat_getSymbols
  427. * @see udat_setSymbols
  428. */
  429. U_CAPI int32_t
  430. udat_countSymbols(    const    UDateFormat                *fmt,
  431.                             UDateFormatSymbolType    type);
  432.  
  433. /**
  434. * Set the symbols associated with an UDateFormat.
  435. * The symbols are what a UDateFormat uses to represent locale-specific data,
  436. * for example month or day names.
  437. * @param fmt The formatter to set
  438. * @param type The type of symbols to set.  One of UDAT_ERAS, UDAT_MONTHS, UDAT_SHORT_MONTHS, 
  439. * UDAT_WEEKDAYS, UDAT_SHORT_WEEKDAYS, UDAT_AM_PMS, or UDAT_LOCALIZED_CHARS
  440. * @param index The index of the symbol to set of type type.
  441. * @param value The new value
  442. * @param valueLength The length of value, or -1 if null-terminated
  443. * @param status A pointer to an UErrorCode to receive any errors
  444. * @return A pointer to result.
  445. * @see udat_getSymbols
  446. * @see udat_countSymbols
  447. */
  448. U_CAPI void
  449. udat_setSymbols(    UDateFormat             *format,
  450.                     UDateFormatSymbolType   type,
  451.                     int32_t                 index,
  452.                     UChar                   *value,
  453.                     int32_t                 valueLength,
  454.                     UErrorCode              *status);
  455.  
  456. #endif
  457.